
//Namespace
package com.katujo.squirrel.annotations;

//Java imports
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * The Squirrel Link annotation is used to mark a field as being 
 * "linked" or having a relation to a parent object. A linked 
 * field (child) can be selected, inserted and deleted together 
 * with the parent object. This is done in the SquirrelManager 
 * via selectLink, insertLink and deleteLink methods. Note that 
 * you have to explicitly call these methods they are not called 
 * internally by the SquirrelManager.
 * 
 * <br/><br/>
 * Copyright 2010 Katujo LTD<br/>
 * Licensed under the Apache License, Version 2.0<br/>
 * (the "License"); you may not use this file except in compliance with the License. You may<br/>
 * obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required <br/>
 * by applicable law or agreed to in writing, software distributed under the License is distributed <br/>
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either <br/>
 * express or implied. See the License for the specific language governing permissions and <br/>
 * limitations under the License. <br/>
 * 
 * @author Johan Hertz
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Link
{
	/**
	 * This is the map telling the SquirrelManager how the parent and
	 * the child are linked. 
	 * <p>
	 * The link is done via key value pairs separated 
	 * by an equals sing(=). The left side is the key and the right side
	 * is the value. The key is the name of the column as it appears in 
	 * the database. The value is either a filed of the child or a constant.
	 * If the value is a constant it needs to be wrapped in single quotas(').
	 * Constant will be parsed as Double, Integer or String.
	 * </p>    
	 * @return The links map.
	 */
	String[] map();
	
	/**
	 * If the field is a map the key is what
	 * filed on the child that will be used as 
	 * a key.
	 * <p>Example: In this case the key of the map will be the 
	 * name field of the child.
	 * @Link(map = {"Parent_ID=id"}, key="name")
	 * private Map<String, Child> children = new HashMap<String, Child>();
	 * </p>
	 * @return The key of the map.
	 */
	String key() default "";
	
	/**
	 * The depth to which the SquirrelManager will
	 * continue with select, inserts and deletes.
	 * <p>
	 * If depth is set to one the children of the 
	 * parent object will be loaded, but not the
	 * grand children of the parent.
	 * </p> 
	 * @return The depth of the link.
	 */
	int depth() default 1;	
	
	/**
	 * The field will only get selected, and is
	 * ignored during inserts and deletes.
	 * @return If link is select only.
	 */
	boolean selectOnly() default false;
}
